cs-arl-xapi

📋 Información General

cs-ARL-xapi es la API oficial de Colmena ARL para la gestión integral de trabajadores dependientes. Esta documentación proporciona información detallada sobre endpoints, parámetros, respuestas y ejemplos de implementación.

🔐 Autenticación

Todos los endpoints requieren autenticación OAuth 2.0 con los siguientes headers obligatorios:

Ejemplo de header invoker:

{
  "application": "Portal",
  "addressIPUser": "192.168.80.13",
  "loginUser": "User",
  "userName": "User Name"
}

🌐 Ambientes Disponibles

🔧 Endpoints

Gestión de Trabajadores

POST /create-dependent-worker

Crea un nuevo registro de trabajador dependiente en el sistema ARL.

URL: https://cs-ARL-xapi-v1-{env}.us-e1.cloudhub.io/api/create-dependent-worker

Parámetros principales:

• consecutiveContractId - ID del contrato (requerido)
• identification - Número de identificación del trabajador (requerido)
• identificationType - Tipo de documento (requerido)
• basicSalary - Salario básico (requerido)
• admissionDate - Fecha de ingreso (requerido)

Respuesta exitosa:

json

{

"filingNumber": 92759247,

"hash": "vUERGIC9UZXh0IC9JbWFnZUIgL0ltYWdlQyAvSW1hZ2VJXQ0KZW5kb2JqDQo2IDAgb2JqD"

}

POST /retired-dependent-workers-cancelled

Procesa el retiro de trabajadores dependientes del sistema.

URL: https://cs-ARL-xapi-v1-{env}.us-e1.cloudhub.io/api/retired-dependent-workers-cancelled

Parámetros principales:

• consecutiveContractId - ID del contrato (requerido)
• identificationType - Tipo de documento (requerido)
• identification - Número de identificación (requerido)
• withdrawalDate - Fecha de retiro (requerido)

Respuesta exitosa:

json

{

"initEffectiveDate": "2023-01-15",

"dateRadicationNew": "2025-06-10",

"filingNumber": "RAD123456",

"hash": "abc123def456..."

}

Servicios de Referencia

GET /obtain-departments

Obtiene el catálogo completo de departamentos colombianos.

Headers requeridos:

• client_id - ID del cliente
• client_secret - Secreto del cliente
• Authorization - Bearer token

GET /cities

Obtiene ciudades por código de departamento.

Parámetros:

• departmentCode - Código del departamento (requerido)

GET /headquarters

Obtiene información de sedes de empresa.

Parámetros:

• consecutiveContract - Número consecutivo del contrato (requerido)

⚠️ Códigos de Respuesta

📝 Validaciones y Reglas de Negocio

Campos Obligatorios

• Todos los campos marcados como "Requerido: Sí" deben estar presentes
• Los formatos de fecha deben ser ISO 8601 (YYYY-MM-DD)
• Los emails deben tener formato válido

Reglas de Negocio

• initEffectiveDate ≤ endEffectiveDate
• admissionDate < endEffectiveDate
• birthdate < admissionDate
• basicSalary > salario mínimo legal vigente

Campo Hash de Seguridad

El campo hash utiliza cifrado SHA-256 y debe generarse con:

SHA256(contractId + workerId + transactionType + transactionDate)

Tipos de transacción:

• C = Crear trabajador
• R = Retirar trabajador

📋 Mejores Prácticas

Seguridad

• Nunca hardcodear credenciales en el código
• Almacenar tokens de forma segura
• Implementar renovación automática de tokens
• Usar HTTPS exclusivamente

Integración

• Implementar manejo robusto de errores
• Usar retry logic para operaciones críticas
• Validar datos antes de enviar requests
• Mantener logs de auditoría completos

Performance

• Cachear datos de referencia (departamentos, ciudades)
• Implementar timeouts apropiados
• Evitar requests innecesarios
• Monitorear latencia y errores

📞 Soporte Técnico

Equipo de Integración Colmena

• 📧 Email: epalma@fgs.co
• 🔗 Portal: MuleSoft Exchange
• 📖 Documentación: Disponible en Anypoint Platform

🔄 Historial de Versiones

💡 Nota: Esta documentación se actualiza regularmente. Para la versión más reciente, consulte el Portal de Exchange.